lets_plot.geo_data.ReverseGeocoder

class lets_plot.geo_data.ReverseGeocoder(lon, lat, level: Optional[Union[str, lets_plot.geo_data.gis.request.LevelKind]], scope=None)

Do not use this class explicitly.

Instead you should construct its objects with special functions: geocode(), geocode_cities(), geocode_counties(), geocode_states(), geocode_countries(), reverse_geocode().

__init__(lon, lat, level: Optional[Union[str, lets_plot.geo_data.gis.request.LevelKind]], scope=None)

Initialize self.

get_boundaries(resolution=None) → GeoDataFrame

Return boundaries for given regions in the form of GeoDataFrame.

Parameters

resolution (int or str) – Boundaries resolution.

Returns

Table of data.

Return type

GeoDataFrame

Note

If resolution has int type, it may take one of the following values:

  • 1-3 for world scale view,

  • 4-6 for country scale view,

  • 7-9 for state scale view,

  • 10-12 for county scale view,

  • 13-15 for city scale view.

Here value 1 corresponds to maximum performance and 15 - to maximum quality.

If resolution is of str type, it may take one of the following values:

  • ‘world’ corresponds to int value 2,

  • ‘country’ corresponds to int value 5,

  • ‘state’ corresponds to int value 8,

  • ‘county’ corresponds to int value 11,

  • ‘city’ corresponds to int value 14.

Here value ‘world’ corresponds to maximum performance and ‘city’ - to maximum quality.

The resolution choice depends on the type of displayed area. The number of objects also matters: one state looks good on a ‘state’ scale while 50 states is a ‘country’ view.

It is allowed to use any resolution for all regions. For example, ‘city’ scale can be used for a state to get a more detailed boundary when zooming in, or ‘world’ for a small preview.

If resolution is not specified (or equal to None), it will be auto-detected. Auto-detection by level_kind is used for geocoding and the number of objects. In this case performance is preferred over quality. The pixelated geometries can be obtained. Use explicit resolution or inc_res() function for better quality.

If the number of objects is equal to n, then resolution will be the following:

  • For countries: if n < 3 then resolution=3, else resolution=1.

  • For states: if n < 3 then resolution=7, if n < 10 then resolution=4, else resolution=2.

  • For counties: if n < 5 then resolution=10, if n < 20 then resolution=8, else resolution=3.

  • For cities: if n < 5 then resolution=13, if n < 50 then resolution=4, else resolution=3.

Examples

1
2
3
4
5
6
7
from IPython.display import display
from lets_plot import *
from lets_plot.geo_data import *
LetsPlot.setup_html()
countries = geocode_countries(['Germany', 'Poland']).inc_res().get_boundaries()
display(countries)
ggplot() + geom_map(aes(fill='found name'), data=countries, color='white')

The geodata is provided by © OpenStreetMap contributors and is made available here under the Open Database License (ODbL).
country found name geometry
0 Germany Deutschland MULTIPOLYGON (((7.47070 49.15297, 7.47070 49.1...
1 Poland Polska MULTIPOLYGON (((23.59863 51.89005, 23.64258 51...
get_centroids() → GeoDataFrame

Return centroids (Point geometry) for given regions in form of GeoDataFrame.

Returns

Table of data.

Return type

GeoDataFrame

Examples

1
2
3
4
5
6
7
from IPython.display import display
from lets_plot import *
from lets_plot.geo_data import *
LetsPlot.setup_html()
countries = geocode_countries(['Germany', 'Poland']).get_centroids()
display(countries)
ggplot() + geom_point(aes(color='found name'), data=countries, size=10)
country found name geometry
0 Germany Deutschland POINT (10.57925 51.16420)
1 Poland Polska POINT (19.15683 51.91905)
get_geocodes() → DataFrame

Return metadata for given regions.

Returns

Table of data.

Return type

DataFrame

Examples

1
2
from lets_plot.geo_data import *
geocode_countries(['Germany', 'Russia']).get_geocodes()
id country found name
0 102955 Germany Deutschland
1 120379 Russia Россия
get_limits() → GeoDataFrame

Return bboxes (Polygon geometry) for given regions in form of GeoDataFrame. For regions intersecting anti-meridian bbox will be divided into two parts and stored as two rows.

Returns

Table of data.

Return type

GeoDataFrame

Examples

1
2
3
4
5
6
7
from IPython.display import display
from lets_plot import *
from lets_plot.geo_data import *
LetsPlot.setup_html()
countries = geocode_countries(['Germany', 'Poland']).get_limits()
display(countries)
ggplot() + geom_rect(aes(fill='found name'), data=countries, color='white')
country found name geometry
0 Germany Deutschland POLYGON ((15.04181 47.27011, 15.04181 55.05857...
1 Poland Polska POLYGON ((24.14578 49.00205, 24.14578 54.83565...
inc_res(delta=2)

Increase auto-detected resolution for boundaries.

Parameters

delta (int, default=2) – Value that will be added to auto-detected resolution.

Returns

Geocoder object specification.

Return type

Geocoder

Examples

1
2
3
4
5
6
7
from IPython.display import display
from lets_plot import *
from lets_plot.geo_data import *
LetsPlot.setup_html()
countries = geocode_countries(['Germany', 'Poland']).inc_res().get_boundaries()
display(countries)
ggplot() + geom_map(aes(fill='found name'), data=countries, color='white')
country found name geometry
0 Germany Deutschland MULTIPOLYGON (((7.47070 49.15297, 7.47070 49.1...
1 Poland Polska MULTIPOLYGON (((23.59863 51.89005, 23.64258 51...